NumberFormatter

The NumberFormatter class provides comprehensive number formatting capabilities with support for decimal, currency, and percentage styles. It handles thousands separators, decimal places, units, negative signs, and multi-locale support.

Constructor

new NumberFormatter(style, options)

Parameters

Property	Type	Required	Description
style	'decimal' | 'currency' | 'percent'	true	The formatting style to use
options	Object	false	Style-specific formatting options

Formatting Styles

Decimal Style

Format numbers with customizable decimal places, thousands separators, and units.

const formatter = new NumberFormatter('decimal', {
  unit: 'auto',              // Display unit (none, auto, thousands, millions, billions, trillions)
  negativeSign: 'prefixDash', // How to display negative numbers
  thousandSeparator: 'comma', // Thousands separator (none, comma, period, space)
  thousandsGrouping: 3,       // Grouping size for thousands
  decimalSeparator: 'period', // Decimal separator (comma, period)
  decimalDigits: 2            // Number of decimal places
});

Decimal Options

Option	Type	Default	Description
unit	'none' | 'auto' | 'thousands' | 'millions' | 'billions' | 'trillions'	'auto'	Unit to apply to the number
negativeSign	'prefixDash' | 'suffixDash' | 'parentheses'	'prefixDash'	How to display negative numbers
thousandSeparator	'none' | 'comma' | 'period' | 'space'	'comma'	Character for thousands separator
thousandsGrouping	number	3	Number of digits in each group
decimalSeparator	'comma' | 'period'	'period'	Character for decimal separator
decimalDigits	number	2	Number of decimal places to display

Currency Style

Format numbers as currency with support for different currency codes and formatting options.

const formatter = new NumberFormatter('currency', {
  currency: 'USD',            // ISO 4217 currency code
  unit: 'auto',               // Display unit
  negativeSign: 'prefixDash', // How to display negative numbers
  thousandSeparator: 'comma', // Thousands separator
  thousandsGrouping: 3,       // Grouping size
  decimalSeparator: 'period', // Decimal separator
  decimalDigits: 2            // Number of decimal places
});

Currency Options

Option	Type	Default	Description
currency	string	Browser default	ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP', 'INR')
unit	'none' | 'auto' | 'thousands' | 'millions' | 'billions' | 'trillions'	'auto'	Unit to apply to the number
negativeSign	'prefixDash' | 'suffixDash' | 'parentheses'	'prefixDash'	How to display negative numbers
thousandSeparator	'none' | 'comma' | 'period' | 'space'	'comma'	Character for thousands separator
thousandsGrouping	number	3	Number of digits in each group
decimalSeparator	'comma' | 'period'	'period'	Character for decimal separator
decimalDigits	number	2	Number of decimal places to display

Percent Style

Format numbers as percentages (multiplies value by 100 and adds % symbol).

const formatter = new NumberFormatter('percent', {
  negativeSign: 'prefixDash',  // How to display negative numbers
  thousandSeparator: 'comma',  // Thousands separator
  thousandsGrouping: 3,        // Grouping size
  decimalSeparator: 'period',  // Decimal separator
  decimalDigits: 2             // Number of decimal places
});

Percent Options

Option	Type	Default	Description
negativeSign	'prefixDash' | 'suffixDash' | 'parentheses'	'prefixDash'	How to display negative numbers
thousandSeparator	'none' | 'comma' | 'period' | 'space'	'comma'	Character for thousands separator
thousandsGrouping	number	3	Number of digits in each group
decimalSeparator	'comma' | 'period'	'period'	Character for decimal separator
decimalDigits	number	2	Number of decimal places to display

Methods

format()

Formats a single numeric value and returns the formatted string.

format(value: MuzeDatum): string

Parameters:

Property	Type	Required	Description
value	MuzeDatum	true	The numeric value to format

Returns: String - The formatted number

formatterFunc()

Returns a formatter function for use with Muze visualizations.

formatterFunc(): (dataInfo: MuzeType) => string

Returns: Function - A formatter function that can be passed to Muze configuration